home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Magnum One
/
Magnum One (Mid-American Digital) (Disc Manufacturing).iso
/
d12
/
vsix60.exe
/
lha
/
VERNSIX.DOC
< prev
next >
Wrap
Text File
|
1990-10-28
|
75KB
|
2,911 lines
Vern Six's Clipper ToolBox
*********************************
*** SHAREWARE EVALUATION COPY ***
*********************************
October 28, 1990
Release 4.30
Copyright (c) 1988-90 by Vernon E. Six, Jr.
All Rights Reserved World Wide
For the most current version please send $5.00 to: VernSix.Lib,
c/o FrontLine Software, 2908 Forest Hollow Lane #2329, Arlington,
Texas 75080.
Table of contents
Item Page
Licensing Terms and Conditions . . . . . . . . . . . . . . . 4
Disclaimer of Warranty . . . . . . . . . . . . . . . . . . . 5
Introduction . . . . . . . . . . . . . . . . . . . . . . . . 6
Syntax Conventions . . . . . . . . . . . . . . . . . . . . . 7
How my programs are assigned version numbers . . . . . . . . 8
ASK() . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
ASK2() . . . . . . . . . . . . . . . . . . . . . . . . . . 11
CENTER() . . . . . . . . . . . . . . . . . . . . . . . . . 12
DISPMSG() . . . . . . . . . . . . . . . . . . . . . . . . . 13
FAKELOCK . . . . . . . . . . . . . . . . . . . . . . . . . 14
FGBG2N() . . . . . . . . . . . . . . . . . . . . . . . . . 15
FSELECT() . . . . . . . . . . . . . . . . . . . . . . . . . 16
GETCOLOR() . . . . . . . . . . . . . . . . . . . . . . . . 17
GETCOORD . . . . . . . . . . . . . . . . . . . . . . . . . 18
GRABSCRN() . . . . . . . . . . . . . . . . . . . . . . . . 19
HELP . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
INITHELP() . . . . . . . . . . . . . . . . . . . . . . . . 21
INITVERN() . . . . . . . . . . . . . . . . . . . . . . . . 22
MAKEHLP . . . . . . . . . . . . . . . . . . . . . . . . . . 23
N2FGBG() . . . . . . . . . . . . . . . . . . . . . . . . . 24
PUTSCRN() . . . . . . . . . . . . . . . . . . . . . . . . . 25
REMKEY() . . . . . . . . . . . . . . . . . . . . . . . . . 26
SPECTRUM() . . . . . . . . . . . . . . . . . . . . . . . . 27
TEXTCOLR() . . . . . . . . . . . . . . . . . . . . . . . . 28
V_APPEND() . . . . . . . . . . . . . . . . . . . . . . . . 29
V_FLOCK() . . . . . . . . . . . . . . . . . . . . . . . . . 30
V_RLOCK() . . . . . . . . . . . . . . . . . . . . . . . . . 31
V_USE() . . . . . . . . . . . . . . . . . . . . . . . . . . 32
VEDIT() . . . . . . . . . . . . . . . . . . . . . . . . . . 33
VFILT() . . . . . . . . . . . . . . . . . . . . . . . . . . 35
VINDEX() . . . . . . . . . . . . . . . . . . . . . . . . . 36
VMENU() . . . . . . . . . . . . . . . . . . . . . . . . . . 37
VSCRL() . . . . . . . . . . . . . . . . . . . . . . . . . . 38
VSELECT() . . . . . . . . . . . . . . . . . . . . . . . . . 39
VWIND() . . . . . . . . . . . . . . . . . . . . . . . . . . 40
WINDCOLR() . . . . . . . . . . . . . . . . . . . . . . . . 41
Global Variables . . . . . . . . . . . . . . . . . . . . . 42
Reporting bugs . . . . . . . . . . . . . . . . . . . . . . 44
I want your functions . . . . . . . . . . . . . . . . . . . 45
REGISTRATION FORM . . . . . . . . . . . . . . . . . . . . . 46
User Survey . . . . . . . . . . . . . . . . . . . . . . . . 48
Licensing Terms and Conditions
Copyright (c) 1988-90 by Vernon E. Six, Jr.
All Rights Reserved World Wide.
VERNSIX.LIB may only be used and distributed under the following
conditions:
1) You may use VERNSIX.LIB for a period of up to thirty days to
determine its suitability for your needs. If you continue
to use VERNSIX.LIB (or any program with VERNSIX.LIB linked
into it) after a period of thirty days you MUST register
your copy. A registration form is included at the end of
this documentation.
2) When you register your copy of VERNSIX.LIB, you will
receive:
a) the latest version without the "advertisemnet" screen
b) a royalty free run-time license to use VERNSIX.LIB in
any of your applications.
3) You may distribute VERNSIX.LIB provided that no fee is
charged, except for a nominal "diskette" fee or "connect
time" charges. In any event, the entire fee shall not
exceed $10.00. This does NOT apply to commercial packages
developed using VERNSIX.LIB. (see paragraphs 1 and 2)
4) You may NOT use VERNSIX.LIB in conjunction with any
commercial endeavor without
a) registering your copy, and
b) providing a "blurb" line about the author of
VERNSIX.LIB i.e. "This application uses VERNSIX.LIB.
Copyright (c) 1988-90 by Vernon E. Six, Jr." in your
documentation.
5) You may NOT distribute VERNSIX.LIB in modified form.
6) If you distribute VERNSIX.LIB, it MUST be in the original
"archive" as released by the author. You may not add any
files, archive comments, nor may you re-archive it using
some other archive program, etc. This is to ensure that my
software hasn't been tampered with.
4
Disclaimer of Warranty
*** NO WARRANTY ***
Because VERNSIX.LIB is distributed as "SHAREWARE", I provide
absolutely no warranty, to the extent permitted by applicable
state law.
Except when otherwise stated in writing, Vernon E. Six, Jr.,
FrontLine Software and/or other parties provide VERNSIX.LIB "AS
IS" without warranty of any kind, either expressed or implied,
including, but not limited to, the implied warranties of
merchantability and fitness for a particular purpose. The entire
risk as to the quality and performance of VERNSIX.LIB is with
you. Should VERNSIX.LIB prove defective, you assume the cost of
all necessary remedies, repair or correction.
In no event will Vernon E. Six, Jr. and/or FrontLine Software be
responsible in any way for the behavior of modified versions of
VERNSIX.LIB. In no event, unless required by applicable state
law, will Vernon E. Six, Jr., FrontLine Software or any other
party who may distribute VERNSIX.LIB as permitted above, be
liable to you for damages, including any lost profits, lost
monies, or other special, incidental or consequental damages
arising out of the user or inability to use (including but not
limited to loss of data or data being render inaccurate or losses
sustained by third parties or a failure of the program to operate
with any other program) VERNSIX.LIB, even if you have been
advised of the possibility of such damages, or any claim by any
other party.
5
Introduction
Welcome!
Thanks for taking the time to try the Vern Six Clipper ToolBox.
This library contains the bulk of the Clipper functions that I
use on a regular basis. I have developed and tested all of these
functions through many many hours of programming.
Because I am a very firm believer in the ShareWare ("Try before
you buy") system... all the functions contained in my library
are fully-functional, fully-debugged and ready-to-use. You will
not find any crippled or partial functions. Until you register
your copy of VERNSIX.LIB, your applications will display ONE ten
second "advertisement" when they start up. This "advertisement"
is not in the registered versions of VERNSIX.LIB. You might say,
"This is the inducement to register."
If you continue to use VERNSIX.LIB or any program with
VERNSIX.LIB linked into it, for more than a period of thirty
days, you must register your copy by sending $39.95 to the
address listed below. For more information on licensing terms
and conditions please read the section of this document entitled
"Licensing Terms and Conditions".
In general, to use a Vernon Six function, you merely use the
command to call the function in your source code, then link your
application with VernSix.Lib. Only the required code will be
included from the library file, thus eliminating unnecessary
overhead.
I highly suggest that you look at the enclosed VERNDEMO.PRG to
see how to use the functions in this library. VERNDEMO.PRG is a
rather simple program that I think you will find it helpful. A
batch file called MAKEDEMO.BAT is included to ease your compiling
of VERNDEMO.PRG.
*** IMPORTANT: The Vernon Six Library is written entirely in
Clipper using the Summer '87 version. If you are using an
earlier version of Clipper, this library will NOT work properly.
The author may be reached at the following address:
Vernon E. Six, Jr.
c/o FrontLine Software
2908 Forest Hollow Lane #2329
Arlington, Texas 75080
Ph: 214/437-7949 - Voice
817/695-0058 - BBS
CompuServe: 72240,3122
Bix: vsix
FidoNet: 1:124/4003.0
Please feel free to contact me at any time to share your comments
about my software and/or licensing policy.
6
Syntax Conventions
This documentation uses the following syntax conventions:
... Ellipsis means something was omitted.
< > Metavariable: something you must furnish
<exp?> Expression of specific data-type where ? equals C for
character, D for date, N for numeric, M for memo, L for
logical or any type if omitted.
<memvar> Name of a memory variable
[] Optional syntax.
[...] Option may be repeated zero or more times.
| A choice: ON | OFF, Numeric | Date, etc.
7
How my programs are assigned version numbers
With any programming effort there are several phases of
development. The phases that my products go through are listed
below.
Phase 1) Planning & Design
This is where the product is completely laid out. i.e.
Exactly what do we want to accomplish with this product?
What are the major steps necessary to accomplish this? Data
normalization, etc.
Phase 2) Detail definition
During this phase I break the total product into several
much smaller pieces. i.e. What are the database
structures? What will the screens look like? etc.
Phase 3) Program Development
This is phase where I try to put several of the smaller
pieces together. This is also known as the "Alpha" stage of
the product. Several test releases of the product will be
made during this time. These releases are called "Alpha
releases".
An "Alpha" release signifies that new development on the
product has taken place. i.e. new functions & features
have been added since the last "Alpha" release.
Phase 4) Debugging & Final Polishing
This phase begins when all the smaller pieces are in place
and all "Alpha" releases have stopped. This is known as the
"Beta" stage of the product. Several releases of the
product will be made during this time. Each release during
this phase is called a "Beta release".
A "Beta" release signifies that a "bug" has been eliminated
since the last "Beta" release.
Phase 5) Documentation
The user documentation is developed and written.
Phase 6) Release to public
Release to public is the final stage of the product. The
product is thought to be "bug free".
8
Numbering....
1.00.a1 First Alpha release of v1.00 (v1.00 will be a
major release)
1.00.a2 Second Alpha release of v1.00 (added some more
features)
1.00.a3 Third Alpha release of v1.00 (added some more
features)
1.00.b1 First Beta release (stopped adding features, now
concentrating on finding bugs) e.g. Entering
phase 4
1.00.b2 Second Beta release (fixed some bugs)
1.00.b3 Third Beta release (fixed some more bugs)
1.00 First Public release (a/k/a Major Release) No
known bugs!
1.01 Fixed some minor bug(s) that were not detected in
Beta Test stage (usually a spelling error, etc.)
1.10 Fixed some major bug(s) that were not detected in
Beta Test stage OR added some program
functionality that wasn't thought of at
development time.
2.00.a1 First Alpha release of v2.00 (v2.00 will be a
major release) i.e. v2.00 starts back at phase 1.
and is (for all pratical purposes) a new product.
.
.
.
9
ASK()
Description: ASK() prompts the user with a one line question.
ASK() will return a one character response which
can be limited to specific characters. ASK() is
non-screen destructive.
Syntax: <memvar> = ASK( <expC1>, <expC2> [, <expN1> [,
<expN2>] ] )
Pass: <expC1> = Question to ask (do not include the
question mark)
<expC2> = List of acceptable characters (the first
character in the list is used as the default
answer)
<expN1> = Optional: Top row of window
<expN2> = Optional: Left column of window
Return: <expC> = Key the user pressed
Notes: The first letter of <expC2> will be used as the
default answer.
Example: IF ASK("Do you want to continue","YyNn") $ "Nn"
QUIT
ENDIF
.
.
.
See also: ASK2(), DISPMSG(), VWIND()
10
ASK2()
Description: ASK2() prompts the user with a multiple line
question. ASK2() will return a one character
response which can be limited to specific
characters. ASK2() is non-screen destructive.
Syntax: <memvar> = ASK2( <expA>, <expN1>, <expC1>,
<expC2>, <expC3> [, <expN2> [, <expN3>] ] )
Pass: <expA> = Name of array containing question
<expN1> = Number of elements to display
<expC1> = Box Title (top - offset to left)
<expC2> = Box Footnote (bottom - centered)
<expC3> = List of acceptable characters (the first
character in the list is used as the default
answer)
<expN2> = Optional: Top row of window
<expN3> = Optional: Left column of window
Return: <expC> = Key the user pressed
Notes: The first letter of <expC3> will be used as the
default answer.
Example: _msg[1] = "This is line one of the question"
_msg[2] = "This is line two"
_msg[3] = "Which line do you like best"
memvar = ASK2(_msg,3,"Title","Footnote","123")
? "You selected line number" + memvar
.
.
.
See Also: ASK(), DISPMSG(), VWIND()
11
CENTER()
Description: CENTER() allows you to center a string within a
given width.
Syntax: CENTER( <expC> [, <expN>] )
Pass: <expC> = String to be centered
<expN> = Optional: width (default is 80)
Return: <expN> = Position to print string at
Example: The following example would center the string
"This is a test" on line ten of your screen.
censtr = "This is a test"
@ 10,CENTER(censtr) SAY censtr
12
DISPMSG()
Description: Displays a message in a window (centered on the
screen)
Syntax: DISPMSG( <expA>, <expN1>, <expC1>, <expC2> [,
<expN2> [, <expN3>] ] )
Pass: <expA> = Name of array containing message
<expN1> = Number of elements to display
<expC1> = Box Title (top - offset to left)
<expC2> = Box Footnote (bottom - centered)
<expN2> = Optional: Top row of window
<expN3> = Optional: Left column of window
Return: <expL> = Always True
Notes: _msg[] is declared PUBLIC in INITVERN(). The
maximum number of elements you can specify is
twenty (20).
Example: _msg[1] = "This is line one"
_msg[2] = "This is line two"
DISPMSG(_msg,2,"Title","Footnote")
See Also: VWIND()
13
FAKELOCK
Description: Simulates a global network lock for runtime
testing of logic associated with network file
operations.
Syntax: SET KEY xxx TO FAKELOCK
Pass: Nothing
Return: Nothing
Usage: FAKELOCK will force all of the Vern Six network
functions (V_APPEND(), V_FLOCK(), V_RLOCK(),
V_USE()) to act as though they were unsuccessful.
This is useful for testing your program code to
recover from such failures. If the variable
_fakelock is true, FAKELOCK will set it to false
and vice-versa. A non-screen destructive message
will appear telling you whether or not the fake
lock is active or not.
Notes: If you are not programming your application to run
on a multi-user network, you do not need this
procedure.
See also: V_APPEND(), V_FLOCK(), V_RLOCK(), V_USE()
14
FGBG2N()
Description: Converts a foreground/background alphabetic color
sequence to a numeric color as shown in SPECTRUM()
Syntax: <memvar> = FGBG2N( <expC> )
Pass: <expC> = Color to convert
Return: <expN> = Numeric representation of <expC> as
defined in SPECTRUM()
Usage: This function is used primarily in GETCOLOR()
Example: memvar = FGBG2N("W+/N")
.
.
.
See Also: GETCOLOR(), N2FGBG(), SPECTRUM()
15
FSELECT()
Description: FSELECT() allows you to query the user for a
filename matching a wildcard specification. The
user will be able to move a light bar to the
filename that he/she wishes to select.
Syntax: <memvar> = FSELECT( <expC1>, <expN1>, <expN2>,
<expN3>, <expC2>, <expC3> )
Pass: <expC1> = Wildcard of files to display. May
include path. i.e. "C:\TEST\*.*"
<expN1> = Top row of window
<expN2> = Left column of window
<expN3> = Maximum number of file names to display
in window
<expC2> = Box Title (top - offset to left)
<expC3> = Box Footnote (bottom - centered)
Return: <expC> = Filename the user selected.
Example: m e m v a r =
FSELECT("*.FRM",5,5,15,"Title","Footnote")
IF .NOT. EMPTY(memvar)
REPORT FORM &memvar TO PRINT
ENDIF
.
.
.
See Also: VWIND()
16
GETCOLOR()
Description: Prompts the user for the various color schemes
(text and windowed) that he/she wants to use in
your program.
Syntax: GETCOLOR()
Pass: Nothing
Return: <expL> = Always true
Usage: GETCOLOR() will display the full color spectrum on
the screen and ask the user for his/her
preferences while in your program.
See Also: FGBG2N(), N2FGBG(), SPECTRUM()
17
GETCOORD
Description: Allows the user to size a box on the screen
through the use of the cursor control keys.
Returns to the top,left and bottom,right
coordinates to your program.
Syntax: DO GETCOORD WITH <memvarN1>, <memvarN2>,
<memvarN3>, <memvarN4>
Pass: <memvarN1> = Top Row
<memvarN2> = Left Column
<memvarN3> = Bottom Row
<memvarN4> = Right Column
Return: Your variables will be changed to the new values
Usage: When this procedure is called you will see a box
appear on the screen (at the starting coordinates
you specified). The cursor will be in the upper
left hand corner of the box. You may move the
corner around the screen by using the cursor
control keys.
If you press the [HOME] key, the cursor will move
from the upper left corner of the box to the lower
right corner. You can now move this corner of the
box around the screen by using the cursor control
keys. Pressing the [HOME] key will once again
place the cursor in the upper left corner of the
box.
When the box is the size and is in the location
you want, press the [RETURN] key.
Notes: Box remains on screen when procedure returns
Example: top = 5
left = 10
bottom = 20
right = 70
DO GETCOORD WITH top,left,bottom,right
.
.
.
18
GRABSCRN()
Description: Captures contents of the screen (including cursor
location, screen attributes, etc.) to be used in
conjunction with PUTSCRN().
Syntax: GRABSCRN()
Pass: Nothing
Return: <expL> = Always True
Usage: Clipper's SAVE SCREEN command doesn't quite fit
the bill for most screen save operations. i.e.
it doesn't save the cursor position or screen
attributes. GRABSCRN() saves all these important
aspects of your screen and will restore them
properly when you call PUTSCRN().
Example: GRABSCRN()
<memvar> = ASK("Do you want to continue","Yawn")
PUTSCRN()
.
.
.
See Also: PUTSCRN()
19
HELP
Description: HELP provides a non-screen-destructive help screen
based on the calling program and variable name.
Help screens can be added at any time after the
program is compiled, through the use of the
MAKEHLP procedure and are fully "context"
sensitive.
Syntax: SET KEY <expN> TO HELP
Pass: Nothing (other than the normal things passed by
SET KEY) Note: See _helpprg and _helpvar in
Global Variables.
Return: Nothing
Usage: You must call the INITHELP() function prior to
issuing "SET KEY <expN> to HELP". INITVERN() will
open a database with an ALIAS() of "HELP" in the
next available work space. The structure and index
key for this database is listed below.
Field Name Type Len Dec
--------------------------------
PROGRAM Char 10 0
VARIABLE Char 10 0
TOPROW Num 2 0
LEFTCOL Num 2 0
BOTROW Num 2 0
RIGHTCOL Num 2 0
HELPTEXT Memo 10 0
--------------------------------
Index File: HELP.N?X
Index Key: PROGRAM+VARIABLE
Because of the index key of this database, you
should be careful to use a variable only once in
any given program. i.e. If you use the same
variable more than once, you will have the same
help screen for each time it is used.
Notes: If _helpprg or _helpvar are not empty, HELP will
base itself on the values these two variables
contain.
Be sure to include the line "EXTERNAL HELP" in
your main program.
See Also: INITHELP(), MAKEHLP
20
INITHELP()
Description: This function creates the necessary HELP files
(DBF, DBT and N?X) in the next available work
area.
Syntax: INITHELP( [<expC>] )
Pass: <expC> = Optional: Name of keyfile required for
MAKEHLP to work properly. Default =
"VERNSIX.DVP"
Return: <expL> = Always True
Notes: Be sure to include the lines "EXTERNAL HELP" and
"EXTERNAL MAKEHLP" in your main program.
Example: INITHELP("yourfile.txt")
See Also: HELP, MAKEHLP
21
INITVERN()
Description: Initializes the variables used by the various
functions in this library as well as sets the
colors from the configuration database or creates
the configuration database if it doesn't exist.
Syntax: INITVERN( [<expC1>] )
Pass: <expC1> = Optional: Name of configuration database
without the ".DBF" Default = "VERN_CFG"
Return: <expL> = Always True
Notes: INITVERN() must be either the first or second line
in your main program. You must not use INITVERN()
more than once in your program!!
If your application is going to run on a multi-
user network, you must SET EXCLUSIVE OFF prior to
calling INITVERN().
Example: SET EXCLUSIVE OFF
INITVERN("myfile")
.
.
.
or
INITVERN()
.
.
.
See Also: GETCOLOR()
22
MAKEHLP
Description: Allows the developer to design a help screen after
the application is compiled.
Syntax: SET KEY <expN> TO MAKEHLP
Pass: Nothing (other than the normal things passed by
SET KEY) NOTE: See _helpprg, _helpline and
_helpvar in Global Variables Section
Return: Nothing
Usage: When this routine is called, you will see a box
appear on the screen. You should size the box
using the technique described in GETCOORD.
When you have a box that is suitable for your help
window, press [RETURN]. At this point you may
edit the help text as you wish. When you are
done, press Ctrl-W.
Notes: If the file contained in variable "_keyfile" does
not exist, this function will return immediately
and not allow you to create/edit a help screen.
If _helpprg or _helpvar are not empty, MAKEHLP
will base itself on the values these two variables
contain.
Be sure to include the line "EXTERNAL MAKEHLP" in
your main program.
See Also: HELP, INITHELP()
23
N2FGBG()
Description: Converts a numeric color to a
foreground/background alphabetic color sequence as
shown in SPECTRUM()
Syntax: <memvar> = N2FGBG( <expN> )
Pass: <expN> = Color to convert
Return: <expC> = Alphabetic representation of <expN> as
defined in SPECTRUM()
Usage: This function is used primarily in GETCOLOR()
Example: memvar = FGBG2N(31)
.
.
.
See Also: GETCOLOR(), FGBG2N(), SPECTRUM()
24
PUTSCRN()
Description: Restores a screen captured with GRABSCRN()
Syntax: PUTSCRN()
Pass: Nothing
Return: <expL> = Always true
Notes: To clear the GRABSCRN() stack, set the variable
GRABCNT to zero.
Example: GRABSCRN()
memvar = ASK("Do you want to continue","Yawn")
PUTSCRN()
.
.
.
See Also: GRABSCRN()
25
REMKEY()
Description: Removes the reference to VINDEX() from the
specified NTX file.
Syntax: REMKEY( <expC1>, <expC2> )
Pass: <expC1> = The portion of the index key that you
want removed.
<expC2> = Name of the NTX file to remove the key
from.
Return: <expL> = .T. = Success, .F. = Failure
Usage: One of the side effects of using VINDEX(), or
other routines similiar to it, is that the name of
the function is a part of the KEY in the index
file's header. The function in the key only
returns a NULL byte, the mere fact that it is in
the header of the file indiciates that any
operation involving the index file will make
subsequent calls to the function. This will slow
things down. REMKEY() will remove the reference
to the function (VINDEX()) from the NTX file's
header so any operation involving the index file
will no longer make subsequent calls to the
function.
Example: n_temp = 0
USE SAMPLE
INDEX ON WHATEVER + WHATELSE + ;
VINDEX("SAMPLE.NTX",@n_temp) TO SAMPLE
USE && Closes the open DBF and NTX File!!!
c_temp = [ + VINDEX("SAMPLE.NTX",@n_temp) ]
REMKEY(c_temp,"SAMPLE.NTX")
USE SAMPLE INDEX SAMPLE
...
See Also: VINDEX() and VERNDEMO.PRG
26
SPECTRUM()
Description: Displays the complete color spectrum (all possible
colors) on the screen with a number representing
each.
Syntax: SPECTRUM()
Pass: Nothing
Return: <expL> = Always true
Usage: SPECTRUM() is used primarily in GETCOLOR().
See Also: FGBG2N(), GETCOLOR(), N2FGBG()
27
TEXTCOLR()
Description: Sets color to normal text colors as defined by the
configuration database.
Syntax: TEXTCOLR()
Pass: Nothing
Return: <expL> = Always True
Notes: See GETCOLOR().
See Also: VWIND(), WINDCOLR()
28
V_APPEND()
Description: Adds a blank record to the currently selected file
or notifies user if unsuccessful.
Syntax: V_APPEND()
Pass: Nothing
Return: <expL> = .T. if successful, otherwise .F.
Usage: V_APPEND() will try to append a blank record to
the currently selected file. If it is
unsuccessful, a non-screen destructive message
stating "Waiting for busy network. Press any key
to abort." will appear on the screen and
V_APPEND() will continue to endlessly attempt to
append a blank record to the currently selected
database. If the user aborts the operation by
pressing a key, V_APPEND() will return a logical
value of false. If V_APPEND() returns a value of
false, its your job as the programmer to abort the
operation and recover properly.
Notes: Be sure to SET EXCLUSIVE OFF at the top of your
program so that files may be used by more than one
user on your network. If you are not programming
your application to run on a multi-user
application, you do not need this function.
Example: DO WHILE whatever
IF .NOT. V_APPEND()
_msg[1] = "Unable to add blank record"
_msg[2] = "Operation aborted"
DISPMSG(_msg,2,"","")
INKEY(5)
EXIT
ENDIF
.
.
.
ENDDO
.
.
.
See Also: FAKELOCK, V_FLOCK(), V_RLOCK(), V_USE()
29
V_FLOCK()
Description: Locks the currently selected file or notifies the
user if unsuccessful.
Syntax: V_FLOCK()
Pass: Nothing
Return: <expL> = .T. if successful, otherwise .F.
Usage: V_FLOCK() will try to lock the currently selected
file. If it is unsuccessful, a non-screen
destructive message stating "Waiting for busy
network. Press any key to abort." will appear on
the screen and V_FLOCK() will continue to
endlessly attempt to lock the currently selected
database. If the user aborts the operation by
pressing a key, V_FLOCK() will return a logical
value of false. If V_FLOCK() returns a value of
false, its your job as the programmer to abort the
operation and recover properly.
Notes: Be sure to SET EXCLUSIVE OFF at the top of your
program so that files may be used by more than one
user on your network. If you are not programming
your application to run on a multi-user
application, you do not need this function.
Example: DO WHILE whatever
IF .NOT. V_FLOCK()
_msg[1] = "Unable to lock current file"
_msg[2] = "Operation aborted"
DISPMSG(_msg,2,"","")
INKEY(5)
EXIT
ENDIF
.
.
.
ENDDO
.
.
.
See Also: FAKELOCK, V_APPEND(), V_RLOCK(), V_USE()
30
V_RLOCK()
Description: Locks the currently selected record or notifies
the user if unsuccessful.
Syntax: V_RLOCK()
Pass: Nothing
Return: <expL> = .T. if successful, otherwise .F.
Usage: V_RLOCK() will try to lock the currently selected
record. If it is unsuccessful, a non-screen
destructive message stating "Waiting for busy
network. Press any key to abort." will appear on
the screen and V_RLOCK() will continue to
endlessly attempt to lock the currently selected
database. If the user aborts the operation by
pressing a key, V_RLOCK() will return a logical
value of false. If V_RLOCK() returns a value of
false, its your job as the programmer to abort the
operation and recover properly.
Notes: Be sure to SET EXCLUSIVE OFF at the top of your
program so that files may be used by more than one
user on your network. If you are not programming
your application to run on a multi-user
application, you do not need this function.
Example: DO WHILE whatever
IF .NOT. V_RLOCK()
_msg[1] = "Unable to lock current file"
_msg[2] = "Operation aborted"
DISPMSG(_msg,2,"","")
INKEY(5)
EXIT
ENDIF
.
.
.
ENDDO
.
.
.
See Also: FAKELOCK, V_APPEND(), V_FLOCK(), V_USE()
31
V_USE()
Description: Opens a file in the current work area or notifies
the user if unsuccessful. The file can have an
ALIAS specified as well as EXCLUSIVE use set on or
off.
Syntax: V_USE( <expC1>, <expL> [, <expC2>] )
Pass: <expC1> = Name of database to open
<expL> = .T. to open file exclusively
.F. to open file in shared mode
<expC2> = Optional: ALIAS name to assign to the
file
Return: <expL> = .T. if successful, otherwise .F.
Usage: V_USE() will try to open the filename contained in
<expC1> in the mode specified in <expL>. If it is
unsuccessful, a non-screen destructive message
stating "Waiting for busy network. Press any key
to abort." will appear on the screen and V_USE()
will continue to endlessly attempt to open the
file in the mode specified. If the user aborts
the operation by pressing a key, V_USE() will
return a logical value of false. If V_USE()
returns a value of false, its your job as the
programmer to abort the operation and recover
properly. If specified, the filename opened will
have an ALIAS of the value contained in <expC2>.
Notes: Be sure to SET EXCLUSIVE OFF at the top of your
program so that files may be used by more than one
user on your network. If you are not programming
your application to run on a multi-user
application, you do not need this function.
Example: DO WHILE whatever
IF .NOT. V_USE("testfile",.F.)
_msg[1] = "Unable to open file"
_msg[2] = "Operation aborted"
DISPMSG(_msg,2,"","")
INKEY(5)
EXIT
ENDIF
.
.
ENDDO
See Also: FAKELOCK, V_APPEND(), V_FLOCK(), V_RLOCK()
32
VEDIT()
Description: Emulates the dBASE III+ "Edit" command by allowing
the user to page back and forth through the
database records and optionally editing the
selected record.
Syntax: VEDIT( [<expC1>,] <expC2>, <expC3>, [<expL>] )
Pass: <expC1> = Optional: Name of your procedure to
display field descriptions, etc. i.e.
setup the screen.
<expC2> = Name of your procedure to "view" the
currently selected record. If empty,
VEDIT() will return the calling program
a value of 0.
<expC3> = Name of your procedure "edit" the
currently selected record. If empty,
VEDIT() will return to the calling
program a value of 13.
<expL> = Optional: .T. = Database is indexed
.F. = Database not indexed
Return: <expN> = Last key the user pressed (look at
INKEY())
Usage: VEDIT() is very useful for working with a "flat"
database. VEDIT() controls all the moving around
inside your database and will handle SEEKs based
on a pressed key, etc.
"View Mode" active keys
-----------------------
Esc - Exit VEDIT() (returns 27 to calling prg)
Home - Move to first record
End - Move to last record
PgUp - Move to previous record
PgDn - Move to next record
Return - Edit currently displayed record
Del - Delete/Recall currently displayed record
Ins - Append a new record
Any AlphaNumeric character invokes a SEEK to the
first record beginning with the pressed key.
HENCE you must have an INDEX open for the database
prior to calling VEDIT() or pass <expL> with a
value of .F.
Any other key causes VEDIT() to exit and return
33
the value of the pressed key to the calling
program.
Its your job, as the programmer, to place menus
(if desired) on the screen in your procedures
named in <expC2> and <expC3>. Its also your job
to CLEAR GETS or READ in your procedures named in
<expC2> and <expC3>.
WARNING!!! Be certain to set the memory variable
_startrec to the desired starting record prior to
calling VEDIT().
Example: See enclosed VERNDEMO.PRG
34
VFILT()
Description: Provides a non-screen-destructive user interface
to allow the user to select a list of fields,
logical connectives, and comparison constants from
pop up light bar windows.
VFILT draws information from the database open in
the work area currently selected when it is
invoked.
Syntax: VFILT()
Pass: Nothing
Return: <expC> = Desired filter (blank if the user
specified no filter requested)
Usage: VFILT() is designed to provide the uninitiated
user with an easy interface to "filter"
specification building. It is database
independent and limits the choices available in
the light bar menus to those that are applicable
to the variable type selected. As the user
selects fields, relational operators and
comparison constants, the string VFILT() builds is
also displayed on the screen.
VFILT() alone is not a powerful function but when
combined with the macro substitution capabilities
of Clipper, the two become very powerful indeed.
The string returned by VFILT() is suitable for
macro substitution in the SET FILTER TO command as
well as in any FOR clause in any Clipper command
supporting that clause (such as REPORT, SORT,
COPY, LIST, etc..).
Example: USE MASTER INDEX MASTER
SET FILTER TO
userfilt = VFILT()
IF .NOT. EMPTY(userfilt)
SET FILTER TO &userfilt
ENDIF
.
.
.
35
VINDEX()
Description: Provides the programmer with a non-screen
destructive "gas guage" type of chart to show the
user what percentage of the index operation is
complete.
Syntax: VINEX( <expC>, @<expN> )
Pass: <expC> = NTX filename that is being created
@<expN> = Dummy numeric memory variable. Must be
set to zero.
Return: <expC> = Always null
Usage: One of the biggest disadvantages of Clipper is the
inability to show the progress of an index
operation. While it can be argued that the hard
drive access light is sufficient to tell the user
that something is happening, a far greater number
of users will argue to the contrary. In fact,
several users have been known to turn the machine
off while in the middle of a large index
operation. VINDEX() provides a user-friendly "gas
gauge" type of display telling the user exactly
how things are progressing.
Notes: VINDEX() will create two PUBLIC variables that you
need to be aware of... n_Records and n_RecPerCol.
This variables are needed by VINDEX() and you can
remove them after the index operation.
Example: n_temp = 0
USE SAMPLE
INDEX ON WHATEVER + WHATELSE + ;
VINDEX("SAMPLE.NTX",@n_temp) TO SAMPLE
...
...
See Also: REMKEY()
36
VMENU()
Description: Provides the programmer with a very fast and
efficient means of producing "pull-down" menus for
their users. VMENU() is screen-destructive.
Syntax: <memvar> = VMENU( <expAC1>, <expAN1>, <expAN2>,
<expAC2> )
Pass: <expAC1> = List of all available menu options on
all available menus (see VERNDEMO.PRG)
<expAN1> = List of where each menu begins
<expAN2> = List of where each menu ends
<expAC2> = List of messages for each menu option
Return: <expN> = Which element of <expAC1> was selected
Example: See enclosed VERNDEMO.PRG
37
VSCRL()
Description: Allows the user to BROWSE through a database
(seeing a limited number of fields) and
selectively edit records.
Syntax: VSCRL( <expN1>, <expN2>, <expN3>, <expC1>,
<expC2>, <expC3>, <expC4> [, <expL>] )
Pass: <expN1> = Top Row of window
<expN2> = Left Column of window
<expN3> = Maximum number of lines in window
<expC1> = Macro string of field names to be
display on each line Example:
"FIRST+[ ]+LAST"
<expC2> = Your procedure to edit the record when
the user presses the [RETURN] key. If
empty VSCRL() will return to the calling
program a value of 13.
<expC3> = Title for top of window
<expC4> = Footnote for bottom of window
<expL> = Optional: .T. if DBF is indexed
.F. if DBF is not indexed
Return: <expN> = Last key the user pressed (look at
INKEY())
Example: See enclosed VERNDEMO.PRG
38
VSELECT()
Description: Allows the user to select a record from currently
selected database.
Syntax: VSELECT( <expN1>, <expN2>, <expN3>, <expC1>,
<expC2>, <expC3> [, <expL>] )
Pass: <expN1> = Top Row of window
<expN2> = Left Column of window
<expN3> = Maximum number of lines in window
<expC1> = Macro string of field names to be
display on each line Example:
"FIRST+[ ]+LAST"
<expC2> = Title for top of window
<expC3> = Footnote for bottom of window
<expL> = Optional: .T. if DBF is indexed
.F. if DBF is not indexed
Return: <expN> = Record number the user selected
Notes: This function is very similiar to VSCRL(), except
no editing of the database is allowed in
VSELECT().
Example: See enclosed VERNDEMO.PRG
39
VWIND()
Description: Draws a window with optional shadow, color and
custom box
Syntax: VWIND( <expN1>, <expN2>, <expN3>, <expN4>,
<expC1>, <expC2> )
Pass: <expN1> = top row
<expN2> = left column
<expN3> = bottom row
<expN4> = right column
<expC1> = Box Title (top - offset to left)
<expC2> = Box Footnote (bottom - centered)
Return: <expN> = Number of usable spaces in window
Notes: VWIND() will reset the colors screen attributes to
those used in WINDCOLR() when it is done.
Example: memvar = VWIND(1,10,20,70,"Testing","Press a key")
See Also: TEXTCOLR(), WINDCOLR(), GETCOLOR()
40
WINDCOLR()
Description: Sets color to windowed text colors as defined by
the configuration database.
Syntax: WINDCOLR()
Pass: Nothing
Return: <expL> = Always True
See Also: GETCOLOR(), VWIND()
41
Global Variables
----------------
The function INITVERN() sets up the following global variables
for use by several of the functions contained in this library.
THESE VARIABLES MUST BE SET UP PROPERLY OR ELSE YOUR APPLICATION
WILL NOT OPERATE AS EXPECTED!
For the most part you need not concern yourself with these
variables, just know that they exist and you will be fine.
AGAIN: INITVERN() takes care of setting all these up for you.
Name Purpose/Contents
-----------------------------------------------------------------
_nstd <expC> = Normal Text Standard FG/BG
_nenh <expC> = Normal Text Enhanced FG/BG
_nuns <expC> = Normal Text Unselected FG/BG
_wstd <expC> = Windowed Text Standard FG/BG
_wenh <expC> = Windowed Text Enhanced FG/BG
_wuns <expC> = Windowed Text Unselected FG/BG
_wbox <expC> = Window Box FG/BG
_wshd <expC> = Window Shadow FG/BG
_shadow <expN> = 0 - Don't use shadow
1 - Use character shadow
2 - Use true shadow
_shdfill <expC> = Shadow fill character
_boxtype <expN> = 0 - Custom box (see _boxstr)
1 - Single Box
2 - Double Box
3 - Double top and bottom, single sides
4 - Single top and bottom, double sides
5 - Double top, single sides and bottom
6 - Double bottom, single sides and top
7 - Bold box
8+ - no box
_boxstr <expC> = Custom box string to use if _boxtype = 0
_keyfile <expC> = Full name of file that must be present
for MAKEHLP to work.
42
_cfgfile <expC> = Full name of configuration database
(colors, etc.)
GRABCNT <expN> = Number of screens on GRABSCRN() stack
GRABSCRN[20] <expA> = Screen images ( GRABSCRN() stack )
GRABROW[20] <expA> = Cursor row ( GRABSCRN() stack )
GRABCOL[20] <expA> = Cursor column ( GRABSCRN() stack)
GRABCOLR[20] <expA> = Screen attributes ( GRABSCRN() stack )
_msg[20] <expA> = DISPMSG message array
_startrec <expN> = Starting record for VEDIT, VSCRL, etc.
_helpprg <expC> = Replacement PROGNAME variable for HELP
and MAKEHLP. This variable is handy if you want
to override such PROGNAMEs as ACHOICE(), etc.
_helpvar <expC> = Replacement VARNAME variable for HELP and
MAKEHLP. This variable is handy if you want to
override such VARNAMEs as ACHOICE(), etc.
_fakelock <expL> = .T. - Simulate network lock, .F. - don't
simulate
_network <expL> = .T. - Force VEDIT() to continue to
redisplay current record while in view mode.
.F. - Function normally
gn_pulldown <expN> = Used with VMENU (which pull-down are we
on?
gn_option <expN> = Used with VMENU (which option are we on?)
43
Reporting bugs
--------------
I very much want to insure that VERNSIX.LIB is free from any
errors. I would appreciate it if you would take the time to
document any errors or anomalies you find in this library. If
you find a "true" error, I will attempt to fix it and then send
you a full-registered copy free of any charge.
Please send comments, critisms and bug reports to:
Vernon E. Six, Jr.
c/o FrontLine Software
2908 Forest Hollow Lane #2329
Arlington, Texas 75080
Ph: 214/437-7949 - Voice
817/695-0058 - BBS
CompuServe: 72240,3122
Bix: vsix
FidoNet: 1:124/4003.0
44
I want your functions
---------------------
If you have developed a function that you would like to see used
in future versions of VERNSIX.LIB, please send it to me on disk
(with source code). If I use your function in the a future
release of VERNSIX.LIB, I will send you a full-registered copy of
VERNSIX.LIB free of any charge.
45
REGISTRATION FORM
-----------------
If you purchased VERNSIX.LIB directly from FrontLine Software in
your own name for $39.95, then your copy is already registered
and you will receive all the benefits of registration. You do
not need to send in a registration form.
If you received VERNSIX.LIB from a "Users' Group", "Software
Library", "SIG", "Bulletin Board", etc. and have paid a small
fee (usually either yearly dues or $3.00 to $10.00 per disk) you
have NOT acquired a registration. The fee you paid was for the
convenience of obtaining the diskette with VERNSIX.LIB on it.
The fee does NOT apply to the registration fee.
If you received an evaluation copy of VERNSIX.LIB from FrontLine
Software for a fee of $5.00, you have NOT acquired a
registration. The $5.00 you paid was for the convenience of
obtaining the diskette with VERNSIX.LIB on it. However, this
$5.00 fee DOES apply toward your registration fee and you may
deduct it from the $39.95 fee when you register.
You may register your copy by filling out the following form and
mailing it to the listed address along with your check or money
order for $39.95 (Texas residents add 8% sales tax).
When you register your copy of VERNSIX.LIB, you will receive the
latest version without the ten second "advertisemnet" in it. You
will also be granted a royalty free run-time license to use
VERNSIX.LIB in any of your applications.
46
VERNSIX.LIB Registration Form v4.30
Send $39.95 (Texas residents add 8% sales tax) check or money
order made payable to Vernon E. Six, Jr to:
Vernon E. Six, Jr.
c/o FrontLine Software
2908 Forest Hollow Lane #2329
Arlington, Texas 75080
Ph: 214/437-7949 - Voice
817/695-0058 - BBS
CompuServe: 72240,3122
Bix: vsix
FidoNet: 1:124/4003.0
Your check will be supporting software distributed under the
ShareWare concept and you will be contributing to the further
development of VERNSIX.LIB and other ShareWare programs.
Name ______________________________________________________
Company ___________________________________________________
Address ___________________________________________________
City/State ________________________________________________
Zip ___________________
Phone ___________________________ Extension ___________
Total Amount Enclosed (please check one):
Non-Texas Residents
__ $39.95
__ $34.95 plus copy of receipt of $5.00 from evaluation copy
Texas Residents (includes 8% sales tax)
__ $43.15
__ $38.15 plus copy of receipt of $5.00 from evaluation copy
Diskette Format: (check one) ___ 5.25" 360kb ___ 3.5" 720kb
47
VERNSIX.LIB Registration Form v4.30 Continued
(User Survey)
What electronic bulletin boards (BBS) do you call? (in order of
preference)
BBS Name City, State Phone Number Max Baud Rate
1. _______________ _________________ _____________ _____________
2. _______________ _________________ _____________ _____________
3. _______________ _________________ _____________ _____________
4. _______________ _________________ _____________ _____________
5. _______________ _________________ _____________ _____________
How did you first learn about VERNSIX.LIB or where did you first
obtain your copy of VERNSIX.LIB? Please be specific.
_________________________________________________________________
_________________________________________________________________
What improvements would you like to see in VERNSIX.LIB?
_________________________________________________________________
_________________________________________________________________
What other Clipper libraries do you currently use? (in order of
preference)
1. ______________________________________________________________
2. ______________________________________________________________
3. ______________________________________________________________
One a scale of one to ten how would you rate VERNSIX.LIB in the
following areas? (1 = poor, 5 = Good, 10 = Excellent)
Performance ____ Professionalism ____ Ease of use ____
Documentation ____ Speed ____ Simplicity ____
48
